用 tool_search + tool_call 让 AI 自己找工具干活 — OpenClaw 动态工具实战

OpenClaw 的工具不是写死在提示词里的,`tool_search` 动态检索、`tool_describe` 读 schema、`tool_call` 原样调用——三件套让 AI 在没见过工具时也能安全上手。

为什么需要「动态工具」

很多 OpenClaw 老用户以为,AI 能用的工具是系统启动时一次性塞进提示词的固定清单。其实不完全是。

OpenClaw 有一类叫 deferred tool(延迟工具)的能力:它们的名字和一句话描述会出现在工具目录里,但完整 schema(参数结构、返回值)按需加载。这套机制的存在,是为了让插件、MCP、客户端工具能在不污染每次对话上下文的前提下,被 AI 在真正需要时拉出来用。

本机 tool_search 返回的就是这样一个目录:它只给你 id、name、label、description、input(参数签名)。注意 input 对部分工具是 unknown 或极简签名——这时候你不能直接硬调,得先 tool_describe 把完整 schema 拉出来。

三件套怎么配合

1. tool_search —— 按能力检索,而不是背名字

tool_search 接受英文查询(lexical 匹配工具名与描述,描述多为英文,所以中文查询通常命中为 0)。一次可以传多个独立 query,也可以传单个 query。

# 我想「在 catalog 里动态搜工具」
tool_search(query="search catalog of available tools dynamically")

返回结构(节选真实字段):

{
  "id": "openclaw:browser:browser",
  "source": "openclaw",
  "sourceName": "browser",
  "name": "browser",
  "label": "Browser",
  "description": "Control the browser via OpenClaw's browser control server...",
  "input": "{ action: string; accept?: boolean; ... }"
}

注意 id 的格式:<source>:<sourceName>:<name>。后面 tool_call 既可以用这个 id,也可以用 name。

2. tool_describe —— 拿到完整参数 schema 再动手

当你要调一个没见过的工具,尤其 input 是 unknown 时,先 tool_describe:

tool_describe(id="openclaw:core:sessions")

它会返回该工具的完整 JSON schema 和元数据,告诉你每个参数是必填还是可选、取值范围、返回结构。这一步是「严禁编造参数」纪律的技术保障——你不必猜,直接读。

3. tool_call —— 原样透传,结果回这里

tool_call(id="openclaw:core:sessions", args={ "action": "list" })

args 是一个对象,把 tool_describe 看到的 schema 原样填进去即可。返回值(含可能的错误对象)会回到本次调用,由 AI 综合成最终答复,不会产生第二次子 agent 回合。

实战踩坑提醒:tool_search 的 query 必须是英文。我实测用中文「搜索可用工具」去查,结果几乎为空;换成英文 search catalog of available tools dynamically 立刻返回一排相关工具。这是 lexical 匹配的语言限制,不是你工具坏了。

一个真实的最小闭环

场景:Agent 想查「当前会话的配置/用量/时间」,但记忆里没有这个工具的精确参数。

tool_search(query="session status model usage time") → 命中 openclaw:core:session_status,签名显示有 sessionKey、model 等可选参数。

直接 tool_call(id="openclaw:core:session_status", args={ "sessionKey": "current" })。

拿到 { model, usage, time, cost, tasks } 之类的结果,合成回复。

全程没有编造参数,因为签名和 tool_describe 都摆在眼前。

和普通工具调用的区别

| 维度 | 普通工具(read/exec/...) | deferred 工具(tool_search/describe/call) |

| --- | --- | --- |

| 出现时机 | 提示词常驻 | 目录常驻,schema 按需 |

| 参数来源 | AI 已知 | 先 search→describe 再 call |

| 典型用途 | 直接干活 | 发现并调用插件/MCP/客户端工具 |

| 返回 | 直接结果 | 经 tool_call 回当前回合 |

简单说:普通工具是「我会」,deferred 工具是「我现在去学」。后者让 Agent 面对未知插件时不会因为「没背过」就罢工。

实战踩坑提醒

别跳过 describe 硬调 unknown 参数工具。 像 sessions 这类 input: unknown 的工具,直接 tool_call 容易填错字段。先 tool_describe 看清楚。

query 用英文,且要具体。 笼统的 tools 会返回整页目录,噪声大;用动词+名词组合(如 search catalog of available tools)更准。

tool_call 的结果可能被层层包装。 很多外部工具返回 { kind, provider, results } 这类结构,取数前先看一眼真实返回,别假设它是扁平数组。

批量查询有总量上限。 多个 query 合并后有效 limit 加起来至多 50,单 query 默认 8。需要更多命中时,分开多查几次。

小结

tool_search + tool_describe + tool_call 是 OpenClaw 的「元工具」三件套:

search 解决「有哪些工具能帮我」;

describe 解决「这个工具怎么用、参数长啥样」;

call 解决「按 schema 原样调,把结果拿回来」。

它把「AI 只能干预设好的活」升级成「AI 能现学现用插件生态里的任何工具」,而且整个过程参数可见、可核对,从源头杜绝编造 API。下次你接入一个新 MCP 或装了个插件却不想改提示词,记得让 Agent 自己搜、自己读、自己调。

扫码关注公众号，获取更多 OpenClaw 实操技巧：

公众号二维码